{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# CaptainAgent\n",
    "By: Jiale Liu, Linxin Song, Jieyu Zhang, Shaokun Zhang\n",
    "\n",
    "In this notebook, we introduce CaptainAgent, an agent enhanced with the capability to call AutoBuild to break down and solve complex tasks. AutoBuild can initiate a group chat between a group of experts and converse to solve the task. The experts in nested chat can be retrieved from agent library. The agents can be equipped with tools for advanced coding.\n",
    "\n",
    "````{=mdx}\n",
    ":::info Requirements\n",
    "Install `ag2` with CaptainAgent:\n",
    "```bash\n",
    "pip install -U ag2[openai,captainagent]\n",
    "```\n",
    "\n",
    "> **Note:** If you have been using `autogen` or `ag2`, all you need to do is upgrade it using:  \n",
    "> ```bash\n",
    "> pip install -U autogen[openai,captainagent]\n",
    "> ```\n",
    "> or  \n",
    "> ```bash\n",
    "> pip install -U ag2[openai,captainagent]\n",
    "> ```\n",
    "> as `autogen`, and `ag2` are aliases for the same PyPI package.  \n",
    "\n",
    "\n",
    "For more information, please refer to the [installation guide](https://docs.ag2.ai/latest/docs/user-guide/basic-concepts/installing-ag2).\n",
    ":::\n",
    "````"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup API endpoint\n",
    "In order to setup API, you should create a OAI_CONFIG_LIST file. The config list should look like the following:\n",
    "```python\n",
    "config_list = [\n",
    "    {\n",
    "        'model': 'gpt-5-nano',\n",
    "        'api_key': '<your OpenAI API key here>',\n",
    "    },\n",
    "    {\n",
    "        'model': 'gpt-3.5-turbo',\n",
    "        'api_key': '<your Azure OpenAI API key here>',\n",
    "        'base_url': '<your Azure OpenAI API base here>',\n",
    "        'api_type': 'azure',\n",
    "        'api_version': '2024-08-01-preview',\n",
    "    },\n",
    "    {\n",
    "        'model': 'gpt-3.5-turbo-16k',\n",
    "        'api_key': '<your Azure OpenAI API key here>',\n",
    "        'base_url': '<your Azure OpenAI API base here>',\n",
    "        'api_type': 'azure',\n",
    "        'api_version': '2024-08-01-preview',\n",
    "    },\n",
    "]\n",
    "```\n",
    "\n",
    "````{=mdx}\n",
    ":::tip\n",
    "Learn more about configuring LLMs for agents [here](https://docs.ag2.ai/latest/docs/user-guide/basic-concepts/llm-configuration).\n",
    ":::\n",
    "````"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import autogen\n",
    "\n",
    "config_path = \"OAI_CONFIG_LIST\"\n",
    "# You can modify the filter_dict to select your model\n",
    "llm_config = autogen.LLMConfig.from_json(path=config_path).where(model=\"gpt-5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using CaptainAgent without libraries\n",
    "We begin with demonstrating how to use CaptainAgent without retrieving from libraries. In this case, CaptainAgent will automatically generate a set of experts according to its identified subtask and initiate the group chat. By default, the backbone of the LLM is set to `gpt-5`. For instructions on configuring the backbone, refer to docs on [`nested_mode`](https://docs.ag2.ai/latest/docs/user-guide/reference-agents/captainagent)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from autogen import UserProxyAgent\n",
    "from autogen.agentchat.contrib.captainagent import CaptainAgent\n",
    "\n",
    "# build agents\n",
    "captain_agent = CaptainAgent(\n",
    "    name=\"captain_agent\",\n",
    "    code_execution_config={\"use_docker\": False, \"work_dir\": \"groupchat\"},\n",
    "    agent_config_save_path=None,  # If you'd like to save the created agents in nested chat for further use, specify the save directory here\n",
    "    llm_config=llm_config,\n",
    ")\n",
    "\n",
    "captain_user_proxy = UserProxyAgent(name=\"captain_user_proxy\", human_input_mode=\"NEVER\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "result = captain_user_proxy.initiate_chat(\n",
    "    captain_agent,\n",
    "    message=\"Find a recent paper about large language models on arxiv and find its potential applications in software.\",\n",
    "    max_turns=1,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Building Agents from library & Retrieve tools from tool library\n",
    "One significant feature of CaptainAgent is that the agents and tools can be retrieved from a dedicated library. When CaptainAgent starts building experts for group chat, it will retrieve and select from agent library, then assign tools retrieved from tool library to the experts.\n",
    "\n",
    "For agent library, refer to [`captainagent_expert_library.json`](https://github.com/ag2ai/ag2/blob/main/notebook/captainagent_expert_library.json) for samples. You can refer to [docs](https://docs.ag2.ai/latest/docs/user-guide/reference-agents/captainagent) on how to customize your own expert library.\n",
    "\n",
    "For tool library, we provide a set of tools [here](https://github.com/ag2ai/ag2/tree/main/autogen/agentchat/contrib/captainagent/tools/README.md), the tools are categorized into three types: data analysis, information_retrieval, math. If you are using the tools, you should [install the requirements](https://github.com/ag2ai/ag2/tree/main/autogen/agentchat/contrib/captainagent/tools/README.md#how-to-use) for them."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using Agent Library Only\n",
    "Below is an example that retrieves experts from library and build nested chat accordingly.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from autogen import UserProxyAgent\n",
    "from autogen.agentchat.contrib.captainagent import CaptainAgent\n",
    "\n",
    "# build agents\n",
    "captain_agent = CaptainAgent(\n",
    "    name=\"captain_agent\",\n",
    "    code_execution_config={\"use_docker\": False, \"work_dir\": \"groupchat\"},\n",
    "    agent_lib=\"captainagent_expert_library.json\",\n",
    "    agent_config_save_path=None,  # If you'd like to save the created agents in nested chat for further use, specify the save directory here\n",
    "    llm_config=llm_config,\n",
    ")\n",
    "\n",
    "captain_user_proxy = UserProxyAgent(name=\"captain_user_proxy\", human_input_mode=\"NEVER\")\n",
    "\n",
    "query = \"find papers on LLM applications from arxiv in the last week, create a markdown table of different domains. After collecting the data, point out future research directions in light of the collected data.\"\n",
    "\n",
    "result = captain_user_proxy.initiate_chat(captain_agent, message=query)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using Both Agent Library and Tool Library\n",
    "Now let's retrieve from both agent library and tool library while building experts for nested chat.\n",
    "\n",
    "To run the following demo, it is required to install the dependencies from the tool library and obtain BING search api and Rapid API key for tools in library to fully function. Please follow the instructions [here](https://docs.ag2.ai/latest/docs/user-guide/reference-agents/captainagent)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The function requires BING api key and Rapid API key to work. You can follow the instructions from docs to get one.\n",
    "import os\n",
    "\n",
    "from autogen import UserProxyAgent\n",
    "from autogen.agentchat.contrib.captainagent import CaptainAgent\n",
    "\n",
    "os.environ[\"BING_API_KEY\"] = \"\"  # set your bing api key here, if you don't need search engine, you can skip this step\n",
    "os.environ[\"RAPID_API_KEY\"] = (\n",
    "    \"\"  # set your rapid api key here, in order for this example to work, you need to subscribe to the youtube transcription api(https://rapidapi.com/solid-api-solid-api-default/api/youtube-transcript3)\n",
    ")\n",
    "\n",
    "# build agents\n",
    "captain_agent = CaptainAgent(\n",
    "    name=\"captain_agent\",\n",
    "    code_execution_config={\"use_docker\": False, \"work_dir\": \"groupchat\"},\n",
    "    agent_lib=\"captainagent_expert_library.json\",\n",
    "    tool_lib=\"default\",\n",
    "    agent_config_save_path=None,  # If you'd like to save the created agents in nested chat for further use, specify the save directory here\n",
    "    llm_config=llm_config,\n",
    ")\n",
    "\n",
    "captain_user_proxy = UserProxyAgent(name=\"captain_user_proxy\", human_input_mode=\"NEVER\")\n",
    "\n",
    "query = \"\"\"# Task\n",
    "Your task is to solve a question given by a user.\n",
    "\n",
    "# Question\n",
    "Examine the video at https://www.youtube.com/watch?v=1htKBjuUWec.\n",
    "\n",
    "What does Teal'c say in response to the question \"Isn't that hot?\"\n",
    "\"\"\".strip()\n",
    "result = captain_user_proxy.initiate_chat(captain_agent, message=query)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The ground truth answer to the question is 'Extremely', which the CaptainAgent answers correctly. Notably, with the assistance of tools, the agent can answer video-related questions. This shows the huge potential of what user customized tools can bring."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Further Reading\n",
    "For a full list of the configurables and the functionalities in CaptainAgent, please refer [here](https://docs.ag2.ai/latest/docs/user-guide/reference-agents/captainagent).\n",
    "\n",
    "For how to customize your own agent library, check [here](https://docs.ag2.ai/latest/docs/user-guide/reference-agents/captainagent).\n",
    "\n",
    "For how to implement your own tool library that suits your need, check the documents [here](https://docs.ag2.ai/latest/docs/user-guide/reference-agents/captainagent).\n"
   ]
  }
 ],
 "metadata": {
  "front_matter": {
   "description": "Introducing CaptainAgent, a powerful agent that can manage and orchestrate other agents and tools to solve complex tasks.",
   "tags": [
    "autobuild",
    "CaptainAgent"
   ]
  },
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
